New Operations manual front page #2183

lidiazuin · 2025-03-17T14:25:28Z

Proposition of a new front page for the operations manual including recommended resources and most visited pages.

modules/ROOT/pages/index.adoc

recrwplay · 2025-03-17T14:27:08Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-operations-2183.surge.sh

Updated pages:

Neo4j operations

NataliaIvakina

I think it looks very good and promising. I left some comments and will help with the list for COSI.

modules/ROOT/pages/index.adoc

NataliaIvakina · 2025-03-18T13:41:10Z

modules/ROOT/pages/index.adoc

+== Tutorials & How-to guides
+
+[.icon]
+image:ga-home.svg[]


Is it possible to reduce this image and turn it into a small icon? Maybe it's only me but it occupies a lot of space.

I can't see your screenshot, unfortunately. Can you send it to me over Slack so I understand what you mean?

modules/ROOT/pages/index.adoc

renetapopova · 2025-03-19T09:38:29Z

Hey, @lidiazuin, thanks a lot for your effort. I think we are going in a good direction.
Having a landing page will benefit users if we give them quick access to pages/sections in the manual that are not visible from the left-hand navigation bar or that can be called differently. Think of this as the Operations Manual cheat sheet.

On Friday, David Pond and I went over the Miro board, and we agreed that it makes sense only if we put the right content there. So, this is what we agreed on, and this is what I tried to also show on the board.

What we need is:

everything to be visible without scrolling. If that's not possible, then with minimum scrolling, let's say one screen and a half. Given the number of links that we want to add, no more than 4 cards (like the ones on https://neo4j.com/docs/) organized in a way that no scrolling is needed, if possible.
Cards include only:

How-tos / Tutorials
Cypher administration commands
Reference pages
Neo4j Admin commands

each card can have a small icon like the ones on https://neo4j.com/docs/, the title, and the links. No other text.
they should be ordered the way they are ordered on the Miro board
COSI should be removed
Natalia and I reworked the Miro board to try to accommodate all the information without scrolling the page.
And below the cards, we can have these three lines:
The latest version of Neo4j is 2025.02.0.
© 2025
Documentation license: Creative Commons 4.0
The license to link to the full license, not the docs home page about licenses.

modules/ROOT/pages/index.adoc

recrwplay · 2025-03-19T10:37:49Z

Documentation license: Creative Commons 4.0
The license to link to the full license, not the docs home page about licenses.

We've just updated the license page with additional information. Why do we want this manual to not link to our own license page (which includes a link to the full CC license text)?

Co-authored-by: NataliaIvakina <[email protected]>

renetapopova · 2025-03-19T10:50:01Z

Documentation license: Creative Commons 4.0
The license to link to the full license, not the docs home page about licenses.

We've just updated the license page with additional information. Why do we want this manual to not link to our own license page (which includes a link to the full CC license text)?
Because I think the Operations manual is only interested in the Creative Commons 4.0 license, and if someone really wants to read it, they would rather read it in full than a summary created by us. Also, users need to read half the page to find the link to the actual license.

lidiazuin · 2025-03-19T10:59:58Z

Hi @renetapopova thanks for your input!

Given the number of links that we want to add, no more than 4 cards

So, the current layout is set to have only three cards in one line, like in neo4j.com/docs. If you want four lists, the option is to use the widget that we have now with the four lists (Neo4j admin commands, Cypher admin commands, etc). I will update the PR so you can see how it would look without the COSI option.

Because I think the Operations manual is only interested in the Creative Commons 4.0 license, and if someone really wants to read it, they would rather read it in full than a summary created by us. Also, users need to read half the page to find the link to the actual license.

It was a legal demand that we use this kind of link now, all manuals need to refer to this page because the whole documentation now needs to be under these same notices and licenses. Please refer to David for more details, we worked together to come up with this.

renetapopova · 2025-03-19T11:23:12Z

Hi @renetapopova thanks for your input!

Given the number of links that we want to add, no more than 4 cards

So, the current layout is set to have only three cards in one line, like in neo4j.com/docs. If you want four lists, the option is to use the widget that we have now with the four lists (Neo4j admin commands, Cypher admin commands, etc). I will update the PR so you can see how it would look without the COSI option.

Because I think the Operations manual is only interested in the Creative Commons 4.0 license, and if someone really wants to read it, they would rather read it in full than a summary created by us. Also, users need to read half the page to find the link to the actual license.

It was a legal demand that we use this kind of link now, all manuals need to refer to this page because the whole documentation now needs to be under these same notices and licenses. Please refer to David for more details, we worked together to come up with this.

We have updated the Miro board to include three cards. Below them, we can add the Neo4j Admin command in four columns.

renetapopova

Some comments on the intro sentences.

modules/ROOT/pages/index.adoc

renetapopova

It's starting to look very nice. I added some more comments.

modules/ROOT/pages/index.adoc

renetapopova · 2025-03-19T13:35:14Z

modules/ROOT/pages/index.adoc

+[.display.cards]

-For all information on *upgrading and migrating Neo4j*, see the link:{neo4j-docs-base-uri}/upgrade-migration-guide/current/[Neo4j Upgrade and Migration Guide].
+== Install, deploy and operate Neo4j in a self-managed environment


Looks much better now.
However, I still think that having an intro sentence looks better than starting with "For more information...". If we have to remove something, then let's remove these two sentences:
"For information on upgrading and migrating Neo4j, see the link:https://neo4j.com/docs/upgrade-migration-guide/[Neo4j Upgrade and Migration] documentation.
For link:https://neo4j.com/aura/[Aura], the Neo4j fully managed cloud service, see the link:https://neo4j.com/docs/aura[Neo4j Aura] documentation."

You mean keeping only the info about the current Neo4j version then?

No, I mean removing this heading: Install, deploy and operate Neo4j in a self-managed environment and having a sentence instead like I already suggested:

Suggested change

== Install, deploy and operate Neo4j in a self-managed environment

Neo4j Operations includes all the operational details and instructions for installing, deploying, and operating Neo4j in a self-managed environment.

The latest version of Neo4j is *{neo4j-version-exact}*.

I can add the introductory sentence, but the layout has this formatting and we should stick to a more standardizing approach.

But who created this layout? Can't we amend it to suit our needs? Or we can have slightly different layouts for different needs/manuals?

Sebastian from the design team created this, DocOps executes it. We can make amends when necessary for a functional reason, which I believe it's not the case here. We need to make sure we follow a standard and create consistency across all docsets.

Co-authored-by: Reneta Popova <[email protected]>

renetapopova

Some more comments

renetapopova · 2025-03-19T15:12:26Z

modules/ROOT/pages/index.adoc

+[.display.cards]

-For all information on *upgrading and migrating Neo4j*, see the link:{neo4j-docs-base-uri}/upgrade-migration-guide/current/[Neo4j Upgrade and Migration Guide].
+== Install, deploy and operate Neo4j in a self-managed environment


No, I mean removing this heading: Install, deploy and operate Neo4j in a self-managed environment and having a sentence instead like I already suggested:

Suggested change

== Install, deploy and operate Neo4j in a self-managed environment

Neo4j Operations includes all the operational details and instructions for installing, deploying, and operating Neo4j in a self-managed environment.

The latest version of Neo4j is *{neo4j-version-exact}*.

modules/ROOT/pages/index.adoc

neo-technology-commit-status-publisher · 2025-03-20T11:22:51Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-operations-2183.surge.sh

Updated pages:

Neo4j Operations

renetapopova · 2025-03-21T11:14:19Z

modules/ROOT/pages/index.adoc

-Documentation license: <<license, Creative Commons 4.0>>
-endif::[]
+[.link]
+link:https://neo4j.com/docs/license[Licenses and disclaimers]


Hey, @davidoliverSP2, this is what we've been talking about. Could you be able to check with legal if we need the licenses on each manual at all, and, if we need them, whether we could link to the licenses that apply to this manual directly or at least to a specific docs' page where only this license is explained? If I am a user, I would rather read the whole license instead of a company's summary of it, but if the legal think that this is needed, that's fine with me. I just think it should be easy for the user to see what licenses we comply with.

lidiazuin · 2025-04-08T13:47:20Z

Closing this PR in favor of the upcoming re-architecture work.

neo4j-docops-agent · 2025-04-08T13:47:55Z

Thanks for the documentation updates.

The preview documentation has now been torn down - reopening this PR will republish it.

New Operations manual front page

6ef008b

lidiazuin added the cherry-pick-this-to-main label Mar 17, 2025

lidiazuin requested review from NataliaIvakina and renetapopova March 17, 2025 14:25

lidiazuin commented Mar 17, 2025

View reviewed changes

modules/ROOT/pages/index.adoc Outdated Show resolved Hide resolved

lidiazuin commented Mar 17, 2025

View reviewed changes

modules/ROOT/pages/index.adoc Outdated Show resolved Hide resolved

lidiazuin commented Mar 17, 2025

View reviewed changes

modules/ROOT/pages/index.adoc Outdated Show resolved Hide resolved

NataliaIvakina reviewed Mar 19, 2025

View reviewed changes

modules/ROOT/pages/index.adoc Outdated Show resolved Hide resolved

Apply suggestions from code review

3d867b7

Co-authored-by: NataliaIvakina <[email protected]>

neo4j deleted a comment from neo-technology-commit-status-publisher Mar 19, 2025

Removing caption and adding Neo4j current version

a651258

lidiazuin added 3 commits March 19, 2025 12:06

New option of the page

b4f0681

Previous version for checking

691042e

changing file name

8ddb5a2

renetapopova requested changes Mar 19, 2025

View reviewed changes

lidiazuin added 2 commits March 19, 2025 13:16

new iteration of the frontpage

e22c360

fixing images and removing unused ones

7e912b8

renetapopova requested changes Mar 19, 2025

View reviewed changes

Apply suggestions from code review

6dcf495

Co-authored-by: Reneta Popova <[email protected]>

renetapopova requested changes Mar 19, 2025

View reviewed changes

update after review

37d099e

renetapopova added NOT_READY_FOR_MERGE WIP labels Mar 20, 2025

Editorial and content updates

c258557

renetapopova self-requested a review March 20, 2025 14:40

renetapopova reviewed Mar 21, 2025

View reviewed changes

lidiazuin closed this Apr 8, 2025

-== Install, deploy and operate Neo4j in a self-managed environment
+Neo4j Operations includes all the operational details and instructions for installing, deploying, and operating Neo4j in a self-managed environment.
+The latest version of Neo4j is *{neo4j-version-exact}*.

New Operations manual front page #2183

New Operations manual front page #2183

Uh oh!

Conversation

lidiazuin commented Mar 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

recrwplay commented Mar 17, 2025

Uh oh!

NataliaIvakina left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

renetapopova commented Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

recrwplay commented Mar 19, 2025

Uh oh!

renetapopova commented Mar 19, 2025

Uh oh!

lidiazuin commented Mar 19, 2025

Uh oh!

renetapopova commented Mar 19, 2025

Uh oh!

renetapopova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

renetapopova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

renetapopova left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

neo-technology-commit-status-publisher commented Mar 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lidiazuin commented Apr 8, 2025

Uh oh!

renetapopova commented Mar 19, 2025 •

edited

Loading